/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.catalina;

import java.io.File;
import java.util.concurrent.ExecutorService;
import java.util.regex.Pattern;


/**
 * A <b>Host</b> is a Container that represents a virtual host in the
 * Catalina servlet engine.  It is useful in the following types of scenarios:
 * <ul>
 * <li>You wish to use Interceptors that see every single request processed
 *     by this particular virtual host.
 * <li>You wish to run Catalina in with a standalone HTTP connector, but still
 *     want support for multiple virtual hosts.
 * </ul>
 * In general, you would not use a Host when deploying Catalina connected
 * to a web server (such as Apache), because the Connector will have
 * utilized the web server's facilities to determine which Context (or
 * perhaps even which Wrapper) should be utilized to process this request.
 * <p>
 * The parent Container attached to a Host is generally an Engine, but may
 * be some other implementation, or may be omitted if it is not necessary.
 * <p>
 * The child containers attached to a Host are generally implementations
 * of Context (representing an individual servlet context).
 *
 * @author Craig R. McClanahan
 */
// 主机是在Catalina servlet引擎中表示虚拟主机的容器。
// 它在以下类型的场景中非常有用: 您希望使用拦截器来查看这个特定虚拟主机处理的每个请求。
// 您希望使用独立的HTTP连接器运行Catalina，但仍然希望支持多个虚拟主机。
// 一般来说，当部署连接到web服务器(如Apache)的Catalina时，您不会使用主机，
// 因为连接器将利用web服务器的设施来确定应该使用哪个上下文(甚至可能是哪个包装器)来处理这个请求。
// 附加到主机的父容器通常是一个引擎，但也可以是一些其他实现，或者如果没有必要可以省略。
// 附加到Host的子容器通常是Context的实现(表示一个单独的servlet上下文)。

// 一个Engine代表一个tomcat
// 一个Host代表一个虚拟主机
// 一个Context代表一个应用
// 一个Wrapper代表一个Servlet
public interface Host extends Container {


    // ----------------------------------------------------- Manifest Constants


    /**
     * The ContainerEvent event type sent when a new alias is added
     * by <code>addAlias()</code>.
     */
    // addAlias()添加新别名时发送的ContainerEvent事件类型
    String ADD_ALIAS_EVENT = "addAlias";


    /**
     * The ContainerEvent event type sent when an old alias is removed
     * by <code>removeAlias()</code>.
     */
    // 当旧别名被removeAlias()删除时发送的ContainerEvent事件类型
    String REMOVE_ALIAS_EVENT = "removeAlias";


    // ------------------------------------------------------------- Properties


    /**
     * @return the XML root for this Host.  This can be an absolute
     * pathname or a relative pathname.
     * If null, the base path defaults to
     * ${catalina.base}/conf/&lt;engine name&gt;/&lt;host name&gt; directory
     */
    // 返回: 这个主机的XML根目录。
    // 这可以是一个绝对路径名或相对路径名。
    // 如果为空，则基本路径默认为${catalina。Base}/conf/引擎名> / 主机名> 目录 主机名> 引擎名>
    String getXmlBase();

    /**
     * Set the Xml root for this Host.  This can be an absolute
     * pathname or a relative pathname.
     * If null, the base path defaults to
     * ${catalina.base}/conf/&lt;engine name&gt;/&lt;host name&gt; directory
     * @param xmlBase The new XML root
     */
    // 为这个主机设置Xml根目录。这可以是一个绝对路径名或相对路径名。如果为空，则基本路径默认为${catalina。Base}/conf/引擎名> / 主机名> 目录
    // 参数: xmlBase -新的XML根 主机名> 引擎名>
    void setXmlBase(String xmlBase);

    /**
     * @return a default configuration path of this Host. The file will be
     * canonical if possible.
     */
    // 返回: 主机的默认配置路径。
    // 如果可能，该文件将是规范的。
    File getConfigBaseFile();

    /**
     * @return the application root for this Host.  This can be an absolute
     * pathname, a relative pathname, or a URL.
     */
    // 返回: 该主机的应用程序根目录。
    // 这可以是一个绝对路径名、一个相对路径名或一个URL。
    String getAppBase();


    /**
     * @return an absolute {@link File} for the appBase of this Host. The file
     * will be canonical if possible. There is no guarantee that that the
     * appBase exists.
     */
    // 返回: 此主机的appBase的绝对文件。
    // 如果可能，该文件将是规范的。不能保证appBase存在。
    File getAppBaseFile();


    /**
     * Set the application root for this Host.  This can be an absolute
     * pathname, a relative pathname, or a URL.
     *
     * @param appBase The new application root
     */
    // 为该主机设置应用程序根目录。
    // 这可以是一个绝对路径名、一个相对路径名或一个URL。
    // 参数: appBase -新的应用程序根目录
    void setAppBase(String appBase);


    /**
     * @return the value of the auto deploy flag.  If true, it indicates that
     * this host's child webapps should be discovered and automatically
     * deployed dynamically.
     */
    // 返回: 自动部署标志的值。
    // 如果为真，则表示该主机的子webapps应该被发现并自动动态部署。
    boolean getAutoDeploy();


    /**
     * Set the auto deploy flag value for this host.
     *
     * @param autoDeploy The new auto deploy flag
     */
    // 为该主机设置自动部署标志值。
    // 参数: autoDeploy -新的自动部署标志
    void setAutoDeploy(boolean autoDeploy);


    /**
     * @return the Java class name of the context configuration class
     * for new web applications.
     */
    // 返回: 新web应用程序的上下文配置类的Java类名。
    String getConfigClass();


    /**
     * Set the Java class name of the context configuration class
     * for new web applications.
     *
     * @param configClass The new context configuration class
     */
    // 为新的web应用程序设置上下文配置类的Java类名。
    // 参数: configClass -新的上下文配置类
    void setConfigClass(String configClass);


    /**
     * @return the value of the deploy on startup flag.  If true, it indicates
     * that this host's child webapps should be discovered and automatically
     * deployed.
     */
    // 返回: deploy on startup标志的值。
    // 如果为真，则表示该主机的子webapps应该被发现并自动部署。
    boolean getDeployOnStartup();


    /**
     * Set the deploy on startup flag value for this host.
     *
     * @param deployOnStartup The new deploy on startup flag
     */
    // 为该主机设置“部署时启动”标志值。
    // 参数: deployyonstartup -新的部署启动标志
    void setDeployOnStartup(boolean deployOnStartup);


    /**
     * @return the regular expression that defines the files and directories in
     * the host's appBase that will be ignored by the automatic deployment
     * process.
     */
    // 返回: 正则表达式，用于定义自动部署过程将忽略的主机appBase中的文件和目录。
    String getDeployIgnore();


    /**
     * @return the compiled regular expression that defines the files and
     * directories in the host's appBase that will be ignored by the automatic
     * deployment process.
     */
    // 返回: 编译后的正则表达式，它定义了自动部署过程将忽略的主机appBase中的文件和目录。
    Pattern getDeployIgnorePattern();


    /**
     * Set the regular expression that defines the files and directories in
     * the host's appBase that will be ignored by the automatic deployment
     * process.
     *
     * @param deployIgnore A regular expression matching file names
     */
    // 设置正则表达式，用于定义自动部署过程将忽略的主机appBase中的文件和目录。
    // 参数: deployIgnore -匹配文件名的正则表达式
    void setDeployIgnore(String deployIgnore);


    /**
     * @return the executor that is used for starting and stopping contexts. This
     * is primarily for use by components deploying contexts that want to do
     * this in a multi-threaded manner.
     */
    // 返回: 用于启动和停止上下文的执行程序。
    // 这主要供部署希望以多线程方式执行此操作的上下文的组件使用。
    ExecutorService getStartStopExecutor();


    /**
     * Returns <code>true</code> if the Host will attempt to create directories for appBase and xmlBase
     * unless they already exist.
     * @return true if the Host will attempt to create directories
     */
    // 如果主机试图为appBase和xmlBase创建目录，除非它们已经存在，则返回true。
    // 返回: 如果主机将尝试创建目录，则返回true
    boolean getCreateDirs();


    /**
     * Should the Host attempt to create directories for xmlBase and appBase
     * upon startup.
     *
     * @param createDirs The new value for this flag
     */
    // 主机是否在启动时尝试为xmlBase和appBase创建目录。
    // 参数: createDirs -该标志的新值
    void setCreateDirs(boolean createDirs);


    /**
     * @return <code>true</code> of the Host is configured to automatically undeploy old
     * versions of applications deployed using parallel deployment. This only
     * takes effect is {@link #getAutoDeploy()} also returns <code>true</code>.
     */
    // 返回: 配置为自动取消使用并行部署部署的应用程序的旧版本。
    // 只有当getAutoDeploy()也返回true时才生效
    boolean getUndeployOldVersions();


    /**
     * Set to <code>true</code> if the Host should automatically undeploy old versions of
     * applications deployed using parallel deployment. This only takes effect
     * if {@link #getAutoDeploy()} returns <code>true</code>.
     *
     * @param undeployOldVersions The new value for this flag
     */
    // 如果主机应该自动取消使用并行部署部署的旧版本应用程序的部署，则设置为true。
    // 只有当getAutoDeploy()返回true时才生效。
    // 参数: undeployOldVersions -该标志的新值
    void setUndeployOldVersions(boolean undeployOldVersions);


    // --------------------------------------------------------- Public Methods

    /**
     * Add an alias name that should be mapped to this same Host.
     *
     * @param alias The alias to be added
     */
    // 添加一个应映射到同一主机的别名。
    // 参数: alias -要添加的别名
    void addAlias(String alias);


    /**
     * @return the set of alias names for this Host.  If none are defined,
     * a zero length array is returned.
     */
    // 返回: 此主机的别名集。
    // 如果没有定义，则返回一个长度为零的数组。
    String[] findAliases();


    /**
     * Remove the specified alias name from the aliases for this Host.
     *
     * @param alias Alias name to be removed
     */
    // 从该主机的别名中删除指定的别名。
    // 参数: alias -要删除的别名
    void removeAlias(String alias);
}
